<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Services::Interface</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Class</span>
            Hoodoo::Services::Interface
                <span class="parent">&lt;
                    Object
                </span>
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/services/services/interface_rb.html">lib/hoodoo/services/services/interface.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p><a href="Service.html">Service</a> implementation authors subclass this to
describe the interface that they implement for a particular Resource, as
documented in the Loyalty Platform API.</p>

<p>See class method <a
href="Interface.html#method-c-interface">::interface</a> for details.</p>

    </div>






    <!-- Namespace -->
    <div class="sectiontitle">Namespace</div>
    <ul>
        <li>
          <span class="type">CLASS</span>
          <a href="Interface/ToList.html">Hoodoo::Services::Interface::ToList</a>
        </li>
        <li>
          <span class="type">CLASS</span>
          <a href="Interface/ToListDSL.html">Hoodoo::Services::Interface::ToListDSL</a>
        </li>
    </ul>


    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>A</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-actions">actions</a>,
              </li>
              <li>
                <a href="#method-i-additional_permissions_for">additional_permissions_for</a>
              </li>
          </ul>
        </dd>
        <dt>E</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-embeds">embeds</a>,
              </li>
              <li>
                <a href="#method-i-endpoint">endpoint</a>,
              </li>
              <li>
                <a href="#method-i-errors_for">errors_for</a>
              </li>
          </ul>
        </dd>
        <dt>I</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-interface">interface</a>
              </li>
          </ul>
        </dd>
        <dt>P</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-public_actions">public_actions</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-secure_log_for">secure_log_for</a>
              </li>
          </ul>
        </dd>
        <dt>T</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-to_create">to_create</a>,
              </li>
              <li>
                <a href="#method-c-to_list">to_list</a>,
              </li>
              <li>
                <a href="#method-i-to_list">to_list</a>,
              </li>
              <li>
                <a href="#method-i-to_update">to_update</a>
              </li>
          </ul>
        </dd>
        <dt>U</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-update_same_as_create">update_same_as_create</a>
              </li>
          </ul>
        </dd>
        <dt>V</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-version">version</a>
              </li>
          </ul>
        </dd>
    </dl>








      <!-- Section attributes -->
      <div class="sectiontitle">Attributes</div>
      <table border='0' cellpadding='5'>
          <tr valign='top' id='attribute-c-actions'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>actions</td>
            <td class='attr-desc'><p>Supported action methods as a Set of symbols with one or more of
<code>:list</code>, <code>:show</code>, <code>:create</code>,
<code>:update</code> or <code>:delete</code>. The presence of a Symbol
indicates a supported action. If empty, no actions are supported. The
default is for all actions to be present in the Set.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-additional_permissions'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>additional_permissions</td>
            <td class='attr-desc'><p>A Hash, keyed by String equivalents of the Symbols in
Hoodoo::Services::Middleware::ALLOWED_ACTIONS, where the values are <a
href="Permissions.html">Hoodoo::Services::Permissions</a> instances
describing extended permissions for the related action. See
::additional_permissions_for.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-embeds'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>embeds</td>
            <td class='attr-desc'><p>Array of strings listing allowed embeddable things. Each string matches the
split up comma-separated value for query string <code>_embed</code> or
<code>_reference</code> keys. For example:</p>

<pre><code>...&amp;_embed=foo,bar</code></pre>

<p>…would be valid provided there was an embedding declaration such as:</p>

<pre><code>embeds :foo, :bar
</code></pre>

<p>…which would in turn lead this accessor to return:</p>

<pre><code>[ &#39;foo&#39;, &#39;bar&#39; ]
</code></pre></td>
          </tr>
          <tr valign='top' id='attribute-c-endpoint'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>endpoint</td>
            <td class='attr-desc'><p>Endpoint path as declared by service, without preceding “/”, possibly as a
symbol - e.g. <code>:products</code> for “/<a href="...">products</a>” as
an implied endpoint.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-errors_for'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>errors_for</td>
            <td class='attr-desc'><p>A <a href="../ErrorDescriptions.html">Hoodoo::ErrorDescriptions</a>
instance describing all errors that the interface might return, including
the default set of platform and generic errors. If nil, there are no
additional error codes beyond the default set.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-implementation'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>implementation</td>
            <td class='attr-desc'><p><a href="Implementation.html">Implementation</a> class for the service. An
<a href="Implementation.html">Hoodoo::Services::Implementation</a> subclass
- the class, not an instance of it.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-public_actions'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>public_actions</td>
            <td class='attr-desc'><p>Public action methods as a Set of symbols with one or more of
<code>:list</code>, <code>:show</code>, <code>:create</code>,
<code>:update</code> or <code>:delete</code>. The presence of a Symbol
indicates an action open to the public and not subject to session security.
If empty, all actions are protected by session security. The default is an
empty Set.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-resource'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>resource</td>
            <td class='attr-desc'><p>Name of the resource the interface addresses as a symbol, e.g.
<code>:Product</code>.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-secure_log_for'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>secure_log_for</td>
            <td class='attr-desc'><p>Secure log actions set by <a
href="Interface.html#method-i-secure_log_for">secure_log_for</a> - see that
call for details. The default is an empty Hash.</p></td>
          </tr>
          <tr valign='top' id='attribute-c-to_create'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>to_create</td>
            <td class='attr-desc'><p>A <a href="../Presenters/Object.html">Hoodoo::Presenters::Object</a>
instance describing the schema for client JSON coming in for calls that
create instances of the resource that the service&#39;s interface is
addressing. If <code>nil</code>, arbitrary data is acceptable (the
implementation becomes entirely responsible for data validation).</p></td>
          </tr>
          <tr valign='top' id='attribute-c-to_update'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>to_update</td>
            <td class='attr-desc'><p>A <a href="../Presenters/Object.html">Hoodoo::Presenters::Object</a>
instance describing the schema for client JSON coming in for calls that
modify instances of the resource that the service&#39;s interface is
addressing. If <code>nil</code>, arbitrary data is acceptable (the
implementation becomes entirely responsible for data validation).</p></td>
          </tr>
          <tr valign='top' id='attribute-c-version'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>version</td>
            <td class='attr-desc'><p>Major version of interface as an integer. All service endpoint routes have
“v{version}/” as a prefix, e.g. “/<a href="...">v1/products</a>”.</p></td>
          </tr>
      </table>


    <!-- Methods -->
      <div class="sectiontitle">Class Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-c-to_list">
              <b>to_list</b>()
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-c-to_list" name="method-c-to_list" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>A <a href="Interface/ToList.html">Hoodoo::Services::Interface::ToList</a>
instance describing the list parameters for the interface as a Set of
Strings. See also <a
href="Interface/ToListDSL.html">Hoodoo::Services::Interface::ToListDSL</a>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-to_list_source')" id="l_method-c-to_list_source">show</a>
              </p>
              <div id="method-c-to_list_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 821</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">to_list</span>
  <span class="ruby-ivar">@to_list</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Interface</span><span class="ruby-operator">::</span><span class="ruby-constant">ToList</span>.<span class="ruby-identifier">new</span>
  <span class="ruby-ivar">@to_list</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
      <div class="sectiontitle">Class Protected methods</div>
        <div class="method">
          <div class="title method-title" id="method-c-interface">
              <b>interface</b>( resource, &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-c-interface" name="method-c-interface" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define the subclass Service&#39;s interface. A DSL is used with methods
documented in the Hoodoo::Services::InterfaceDSL class.</p>

<p>The absolute bare minimum interface description just states that a
particular implementation class is used when requests are made to a
particular URL endpoint, which is implementing an interface for a
particular given resource. For a hypothetical Magic resource interface:</p>

<pre><code>class MagicImplementation &lt; Hoodoo::Services::Implementation
  # ...implementation code goes here...
end

class MagicInterface &lt; Hoodoo::Services::Interface
  interface :Magic do
    endpoint :paul_daniels, MagicImplementation
  end
end
</code></pre>

<p>This would cause all calls to URLs at &#39;/<a
href="...">paul_daniels</a>&#39; to be routed to an instance of the
MagicImplementation class.</p>

<p>Addtional DSL facilities allow the interface to say what HTTP methods it
supports (in terms of the action methods that it supports inside its
implementation class), describe any extra sort, search or filter data it
allows beyond the common fields and describe the expected JSON fields for
creation and/or modification actions. By specifing these, the service
middleware code is able to do extra validation and sanitisation of client
requests, but they&#39;re entirely optional if the implementation class
wants to take over all of that itself.</p>
<dl class="rdoc-list note-list"><dt><code>resource</code>
<dd>
<p>Name of the resource that the interface is for, as a String or Symbol (e.g.
<code>:Purchase</code>).</p>
</dd><dt>&amp;block
<dd>
<p>Block that calls the Hoodoo::Services::InterfaceDSL methods; <a
href="Interface.html#method-i-endpoint">endpoint</a> is the only mandatory
call.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-interface_source')" id="l_method-c-interface_source">show</a>
              </p>
              <div id="method-c-interface_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 721</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">interface</span>( <span class="ruby-identifier">resource</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )

  <span class="ruby-keyword">if</span> <span class="ruby-ivar">@to_list</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-ivar">@to_list</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Interface</span><span class="ruby-operator">::</span><span class="ruby-constant">ToList</span>.<span class="ruby-identifier">new</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Hoodoo::Services::Interface subclass unexpectedly ran ::interface more than once&quot;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">resource</span> = <span class="ruby-identifier">resource</span>.<span class="ruby-identifier">to_sym</span>

  <span class="ruby-identifier">interface</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">new</span>
  <span class="ruby-identifier">interface</span>.<span class="ruby-identifier">instance_eval</span> <span class="ruby-keyword">do</span>
    <span class="ruby-identifier">version</span> <span class="ruby-number">1</span>
    <span class="ruby-identifier">embeds</span> <span class="ruby-comment"># Nothing</span>
    <span class="ruby-identifier">actions</span> <span class="ruby-operator">*</span><span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Middleware</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOWED_ACTIONS</span>
    <span class="ruby-identifier">public_actions</span> <span class="ruby-comment"># None</span>
    <span class="ruby-identifier">secure_log_for</span> <span class="ruby-comment"># None</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">interface</span>.<span class="ruby-identifier">instance_eval</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )

  <span class="ruby-keyword">if</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">endpoint</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Hoodoo::Services::Interface subclasses must always call the &#39;endpoint&#39; DSL method in their interface descriptions&quot;</span>
  <span class="ruby-keyword">end</span>

<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-actions">
              <b>actions</b>( *supported_actions )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-actions" name="method-i-actions" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>List the actions that the service implementation supports. If you don&#39;t
call this, the middleware assumes that all actions are available; else it
only calls for supported actions. If you declared an empty array, your
implementation would never be called.</p>
<dl class="rdoc-list note-list"><dt>*supported_actions
<dd>
<p>One or more from <code>:list</code>, <code>:show</code>,
<code>:create</code>, <code>:update</code> and <code>:delete</code>. Always
use symbols, not strings. An exception is raised if unrecognised actions
are given.</p>
</dd></dl>

<p>Example:</p>

<pre><code>actions :list, :show
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-actions_source')" id="l_method-i-actions_source">show</a>
              </p>
              <div id="method-i-actions_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 315</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">actions</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">supported_actions</span> )
  <span class="ruby-identifier">supported_actions</span>.<span class="ruby-identifier">map!</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span>.<span class="ruby-identifier">to_sym</span> }
  <span class="ruby-identifier">invalid</span> = <span class="ruby-identifier">supported_actions</span> <span class="ruby-operator">-</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Middleware</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOWED_ACTIONS</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">invalid</span>.<span class="ruby-identifier">empty?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Services::Interface#actions does not recognise one or more actions: &#39;#{ invalid.join( &#39;, &#39; ) }&#39;&quot;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:actions=</span>, <span class="ruby-constant">Set</span>.<span class="ruby-identifier">new</span>( <span class="ruby-identifier">supported_actions</span> ) )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-additional_permissions_for">
              <b>additional_permissions_for</b>( action, &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-additional_permissions_for" name="method-i-additional_permissions_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declare additional permissions that you require for a given action.</p>

<p>If the implementation of a resource endpoint involves making calls out to
other resources, then you need to consider how authorisation is granted to
those other resources.</p>

<p>The <a href="Session.html">Hoodoo::Services::Session</a> instance for the
inbound external caller carries a Hoodoo::Services::Permission instance
describing the actions that the caller is permitted to do. The middleware
enforces these permissions, so that a resource implementation won&#39;t be
called at all unless the caller has permission to do so.</p>

<p>These permissions continue to apply during inter-resource calls. The wider
session context is always applied. So, if one resource calls another
resource, either:</p>
<ul><li>
<p>The inbound API caller&#39;s session must have all necessary permissions
for both the resource it is actually directly calling, and for any actions
in any resources that the called resource in turn calls (and so-on, for any
chain of resources).</p>
</li></ul>

<p>…or…</p>
<ul><li>
<p>The resource uses this <code>additional_permissions_for</code> method to
declare up-front that it will require the described permissions when a
particular action is performed on it. When an inter-resource call is made,
a temporary internal-only session is constructed that merges the
permissions of the inbound caller with the additional permissions requested
by the resource. The downstream called resource needs no special case code
at all - it just sees a valid session with valid permissions and does what
the upstream resource asked of it.</p>
</li></ul>

<p>For example, suppose a resource Clock returns both a time and a date, by
calling out to the Time and Date resources. One option is that the inbound
caller must have <code>show</code> action permissions for all of Clock,
Time and Date; if any of those are missing, then an attempt to call
<code>show</code> on the Clock resource would result in a 403 response.</p>

<p>The other option is for Clock&#39;s interface to declare its requirements:</p>

<pre><code>additional_permissions_for( :show ) do | p |
  p.set_resource( :Time, :show, Hoodoo::Services::Permissions::ALLOW )
  p.set_resource( :Date, :show, Hoodoo::Services::Permissions::ALLOW )
end
</code></pre>

<p>Suppose you could create Clock instances for some reason, but there was an
audit trail for this; Clock must create an Audit entry itself, but you
don&#39;t want to expose this ability to external callers through their
session permissions; so, just declare your additional permissions for that
specific inter-service case:</p>

<pre><code>additional_permissions_for( :create ) do | p |
  p.set_resource( :Audit, :create, Hoodoo::Services::Permissions::ALLOW )
end
</code></pre>

<p>The call says which action in <em>the</em> <em>declaring</em>
_interface&#39;s_ <em>resource</em> is a target. The block takes a single
parameter; this is a default initialisation <a
href="Permissions.html">Hoodoo::Services::Permissions</a> instance. Use
that object&#39;s methods to set up whatever permissions you need in other
resources, to successfully process the action in question. You only need to
describe the resources you immediately call, not the whole chain - if
“this” resource calls another, then it&#39;s up to the other resource to in
turn describe additional permissions should it make its own set of
downstream calls to further resource endpoints.</p>

<p>Setting default permissions or especially the default permission fallback
inside the block is possible but <strong>VERY</strong>
<strong>STRONGLY</strong> <strong>DISCOURAGED</strong>. Instead, precisely
describe the downstream resources, actions and permissions that are
required.</p>

<p>Note an important restriction - public actions (see <a
href="Interface.html#attribute-c-public_actions">::public_actions</a>)
cannot be augmented in this way. A public action in one resource can only
ever call public actions in other resources. This is because no session is
needed <em>at</em> <em>all</em> to call a public action; calling into a
protected action in another resource from this context would require
invention of a full caller context which would be entirely invented and
could represent an accidental (and significant) security hole.</p>

<p>If you call this method for the same action more than once, the last call
will be the one that takes effect - each call overwrites the results of any
previous call made for the same action.</p>

<p>Parameters are:</p>
<dl class="rdoc-list note-list"><dt><code>action</code>
<dd>
<p>The action in this interface which will require the additional permissions
to be described. Pass a Symbol or equivalent String from the list in
Hoodoo::Services::Middleware::ALLOWED_ACTIONS.</p>
</dd><dt>&amp;block
<dd>
<p>Block which is passed a new, default state <a
href="Permissions.html">Hoodoo::Services::Permissions</a> instance; make
method calls on this instance to describe the required permissions.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-additional_permissions_for_source')" id="l_method-i-additional_permissions_for_source">show</a>
              </p>
              <div id="method-i-additional_permissions_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 668</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">additional_permissions_for</span>( <span class="ruby-identifier">action</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">action</span> = <span class="ruby-identifier">action</span>.<span class="ruby-identifier">to_s</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">block_given?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-string">&#39;Hoodoo::Services::Interface#additional_permissions_for must be passed a block&#39;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">p</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Permissions</span>.<span class="ruby-identifier">new</span>
  <span class="ruby-keyword">yield</span>( <span class="ruby-identifier">p</span> )

  <span class="ruby-identifier">additional_permissions</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">additional_permissions</span>() <span class="ruby-operator">||</span> {}
  <span class="ruby-identifier">additional_permissions</span>[ <span class="ruby-identifier">action</span> ] = <span class="ruby-identifier">p</span>
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:additional_permissions=</span>, <span class="ruby-identifier">additional_permissions</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-embeds">
              <b>embeds</b>( *embeds )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-embeds" name="method-i-embeds" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>An array of supported embed keys (as per documentation, so singular or
plural as per resource interface descriptions in the Loyalty Platform API).
Things which can be embedded can also be referenced, via the
<code>_embed</code> and <code>_reference</code> query string keys.</p>

<p>The middleware uses the list to reject requests from clients which ask for
embedded or referenced entities that were not listed by the interface. If
you don&#39;t call here, or call here with an empty array, no embedding or
referencing will be allowed for calls to the service implementation.</p>
<dl class="rdoc-list note-list"><dt><code>embed</code>
<dd>
<p>Array of permitted embeddable entity names, as symbols or strings. The
order of array entries is arbitrary.</p>
</dd></dl>

<p>Example: An interface permits lists that request embedding or referencing
of “vouchers”, “balances” and “member”:</p>

<pre><code>embed :vouchers, :balances, :member
</code></pre>

<p>As a result, <a href="Interface.html#method-i-embeds">embeds</a> would
return:</p>

<pre><code>[ &#39;vouchers&#39;, &#39;balances&#39;, &#39;member&#39; ]
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-embeds_source')" id="l_method-i-embeds_source">show</a>
              </p>
              <div id="method-i-embeds_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 438</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">embeds</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">embeds</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:embeds=</span>, <span class="ruby-identifier">embeds</span>.<span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span>.<span class="ruby-identifier">to_s</span> } )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-endpoint">
              <b>endpoint</b>( uri_path_fragment, implementation_class )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-endpoint" name="method-i-endpoint" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Mandatory part of the interface DSL. Declare the interface&#39;s URL
endpoint and the <a
href="Implementation.html">Hoodoo::Services::Implementation</a> subclass to
be invoked when client requests are sent to a URL matching the endpoint.</p>

<p>No two interfaces can use the same endpoint within a service application,
unless the describe a different interface version - see <a
href="Interface.html#method-i-version">version</a>.</p>

<p>Example:</p>

<pre><code>endpoint :estimations, PurchaseImplementation
</code></pre>
<dl class="rdoc-list note-list"><dt><code>uri_path_fragment</code>
<dd>
<p>Path fragment to match at the start of a URL path, as a symbol or string,
excluding leading “/”. The URL path matches the fragment if the path starts
with a “/”, then matches the fragment exactly, then is followed by either
“.”, another “/”, or the end of the path string. For example, a fragment of
<code>:products</code> matches all paths out of <code>/products</code>,
<code>/products.json</code> or <code>/products/22</code>, but does not
match <code>/products_and_things</code>.</p>
</dd><dt><code>implementation_class</code>
<dd>
<p>The <a href="Implementation.html">Hoodoo::Services::Implementation</a>
subclass (the class itself, not an instance of it) that should be used when
a request matching the path fragment is received.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-endpoint_source')" id="l_method-i-endpoint_source">show</a>
              </p>
              <div id="method-i-endpoint_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 275</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">endpoint</span>( <span class="ruby-identifier">uri_path_fragment</span>, <span class="ruby-identifier">implementation_class</span> )

  <span class="ruby-comment"># http://www.ruby-doc.org/core-2.2.3/Module.html#method-i-3C</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">implementation_class</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Implementation</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Services::Interface#endpoint must provide Hoodoo::Services::Implementation subclasses, but &#39;#{ implementation_class }&#39; was given instead&quot;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:endpoint=</span>,       <span class="ruby-identifier">uri_path_fragment</span>    )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:implementation=</span>, <span class="ruby-identifier">implementation_class</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-errors_for">
              <b>errors_for</b>( domain, &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-errors_for" name="method-i-errors_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declares custom errors that are part of this defined interface. This calls
directly through to <a
href="../ErrorDescriptions.html#method-i-errors_for">Hoodoo::ErrorDescriptions#errors_for</a>,
so see that for details.</p>

<p>A service should usually define only a single domain of error using one
call to <a href="Interface.html#method-i-errors_for">errors_for</a>, but
techncially can make as many calls for as many domains as required.
Definitions are merged.</p>
<dl class="rdoc-list note-list"><dt><code>domain</code>
<dd>
<p>Domain, e.g. &#39;purchase&#39;, &#39;transaction&#39; - see <a
href="../ErrorDescriptions.html#method-i-errors_for">Hoodoo::ErrorDescriptions#errors_for</a>
for details.</p>
</dd><dt>&amp;block
<dd>
<p>Code block making <a
href="../ErrorDescriptions.html">Hoodoo::ErrorDescriptions</a> DSL calls.</p>
</dd></dl>

<p>Example:</p>

<pre><code>errors_for &#39;transaction&#39; do
  error &#39;duplicate_transaction&#39;, status: 409, message: &#39;Duplicate transaction&#39;, :required =&gt; [ :client_uid ]
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-errors_for_source')" id="l_method-i-errors_for_source">show</a>
              </p>
              <div id="method-i-errors_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 565</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">errors_for</span>( <span class="ruby-identifier">domain</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">descriptions</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">errors_for</span>

  <span class="ruby-keyword">if</span> <span class="ruby-identifier">descriptions</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-identifier">descriptions</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:errors_for=</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">ErrorDescriptions</span>.<span class="ruby-identifier">new</span> )
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">descriptions</span>.<span class="ruby-identifier">errors_for</span>( <span class="ruby-identifier">domain</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-public_actions">
              <b>public_actions</b>( *public_actions )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-public_actions" name="method-i-public_actions" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>List any actions which are public - NOT PROTECTED BY SESSIONS. For public
actions, no X-Session-ID or similar header is consulted and no session data
will be associated with your <a
href="Context.html">Hoodoo::Services::Context</a> instance when action
methods are called.</p>

<p>Use with great care!</p>

<p>Note that if the implementation of a public action needs to call other
resources, it can only ever call them if those actions in those other
resources are also public. The implementation of a public action is
prohibited from making calls to protected actions in other resources.</p>
<dl class="rdoc-list note-list"><dt>*public_actions
<dd>
<p>One or more from <code>:list</code>, <code>:show</code>,
<code>:create</code>, <code>:update</code> and <code>:delete</code>. Always
use symbols, not strings. An exception is raised if unrecognised actions
are given.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-public_actions_source')" id="l_method-i-public_actions_source">show</a>
              </p>
              <div id="method-i-public_actions_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 344</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">public_actions</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">public_actions</span> )
  <span class="ruby-identifier">public_actions</span>.<span class="ruby-identifier">map!</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">item</span>.<span class="ruby-identifier">to_sym</span> }
  <span class="ruby-identifier">invalid</span> = <span class="ruby-identifier">public_actions</span> <span class="ruby-operator">-</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Middleware</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOWED_ACTIONS</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">invalid</span>.<span class="ruby-identifier">empty?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Services::Interface#public_actions does not recognise one or more actions: &#39;#{ invalid.join( &#39;, &#39; ) }&#39;&quot;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:public_actions=</span>, <span class="ruby-constant">Set</span>.<span class="ruby-identifier">new</span>( <span class="ruby-identifier">public_actions</span> ) )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-secure_log_for">
              <b>secure_log_for</b>( secure_log_actions = {} )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-secure_log_for" name="method-i-secure_log_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Set secure log actions.</p>
<dl class="rdoc-list note-list"><dt>secure_log_actions
<dd>
<p>A Hash, described below.</p>
</dd></dl>

<p>The given Hash keys are names of actions as Symbols: <code>:list</code>,
<code>:show</code>, <code>:create</code>, <code>:update</code> or
<code>:delete</code>. Values are <code>:request</code>,
<code>:response</code> or <code>:both</code>. For a given action targeted
at this resource:</p>
<ul><li>
<p>A key of <code>:request</code> means that API call-related <a
href="../../Hoodoo.html">Hoodoo</a> automatic logging will <em>exclude</em>
body data for the <em>inbound</em> <em>request</em>, but still include body
data in the response. Example: A POST to a Login resource includes a
password which you don&#39;t want logged, but the response data doesn&#39;t
quote the password back so is “safe”. The secure log actions Hash for the
Login resource&#39;s interface would include <code>:create =&gt;
:request</code>.</p>
</li><li>
<p>A key of <code>:response</code> means that API call-related <a
href="../../Hoodoo.html">Hoodoo</a> automatic logging will <em>exclude</em>
body data for the <em>outbound</em> <em>response</em>, but still include
body data in the request. Example: A POST to a Caller resource creates a
Caller with a generated authentication secret that&#39;s only exposed in
the POST&#39;s response. The inbound data used to create that Caller can be
safely logged, but the authentication secret is sensitive and shouldn&#39;t
be recorded. The secure log actions Hash for the Caller resource&#39;s
interface would include <code>:create =&gt; :response</code>.</p>

<p><em>ERROR</em> <em>RESPONSES</em> <em>ARE</em> <em>STILL</em>
<em>LOGGED</em> because that&#39;s useful data; so make sure that if you
generate any custom errors in your service that secure data is not
contained within them.</p>
</li><li>
<p>A key of <code>both</code> has the same result as both
<code>:request</code> and <code>:response</code>, so body data is never
logged. It&#39;s hard to come up with good examples of resources where both
the incoming data is sensitive and the outgoing data is sensitive but the
option is included for competion, as someone out there will need it.</p>
</li></ul>

<p>Example: The request body data sent by a caller into a resource&#39;s
<code>:create</code> action will not be logged:</p>

<pre><code>secure_log_for( { :create =&gt; :request } )
</code></pre>

<p>Example: Neither the request data sent by a caller, nor the response data
sent back, will be logged for an <code>:update</code> action:</p>

<pre><code>secure_log_for( { :update =&gt; :both } )
</code></pre>

<p>The default is an empty Hash; all actions have both inbound request body
data and outbound response body data logged by <a
href="../../Hoodoo.html">Hoodoo</a>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-secure_log_for_source')" id="l_method-i-secure_log_for_source">show</a>
              </p>
              <div id="method-i-secure_log_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 404</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">secure_log_for</span>( <span class="ruby-identifier">secure_log_actions</span> = {} )
  <span class="ruby-identifier">secure_log_actions</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Utilities</span>.<span class="ruby-identifier">symbolize</span>( <span class="ruby-identifier">secure_log_actions</span> )
  <span class="ruby-identifier">invalid</span> = <span class="ruby-identifier">secure_log_actions</span>.<span class="ruby-identifier">keys</span> <span class="ruby-operator">-</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Middleware</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOWED_ACTIONS</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">invalid</span>.<span class="ruby-identifier">empty?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Services::Interface#secure_log_for does not recognise one or more actions: &#39;#{ invalid.join( &#39;, &#39; ) }&#39;&quot;</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:secure_log_for=</span>, <span class="ruby-identifier">secure_log_actions</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-to_create">
              <b>to_create</b>( &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-to_create" name="method-i-to_create" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Optional description of the JSON parameters (schema) that the
interface&#39;s implementation requires for calls creating resource
instances. The block uses the DSL from <a
href="../Presenters/Object.html">Hoodoo::Presenters::Object</a>, so you can
specify basic object things like <code>string</code>, or higher level
things like <code>type</code> or <code>resource</code>.</p>

<p>If a call comes into the middleware from a client which contains body data
that doesn&#39;t validate according to your schema, it&#39;ll be rejected
before even getting as far as your interface implementation.</p>

<p>Default values for fields where present are for <em>rendering</em>
<em>only</em>; they are not injected into the inbound body for (say)
persistence at database levels. A returned, rendered representation based
on the same schema would have the default values present only. If you need
default values at the persistence layer too, define them there too with
whatever mechanism is most appropriate for your chosen persistence
approach.</p>

<p>The <a
href="../Presenters/BaseDSL.html#method-i-internationalised">Hoodoo::Presenters::BaseDSL#internationalised</a>
DSL method can be called within your block harmlessly, but it has no side
effects. Any resource interface that can take internationalised data for
creation (or modification) must already have an internationalised
representation, so the standard resources in the <a
href="../Data/Resources.html">Hoodoo::Data::Resources</a> collection will
already have declared that internationalisation applies.</p>

<p>Example 1:</p>

<pre><code>to_create do
  string :name, :length =&gt; 32, :required =&gt; true
  text :description
end</code></pre>

<p>Example 2: With a resource</p>

<pre><code>to_create do
  resource Product # Fields are *inline*
end
</code></pre>
<dl class="rdoc-list note-list"><dt>&amp;block
<dd>
<p>Block, passed to <a
href="../Presenters/Object.html">Hoodoo::Presenters::Object</a>, describing
the fields used for resource creation.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-to_create_source')" id="l_method-i-to_create_source">show</a>
              </p>
              <div id="method-i-to_create_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 499</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">to_create</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">obj</span> = <span class="ruby-constant">Class</span>.<span class="ruby-identifier">new</span>( <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span> )
  <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">schema</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:to_create=</span>, <span class="ruby-identifier">obj</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-to_list">
              <b>to_list</b>( &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-to_list" name="method-i-to_list" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Specify parameters related to common index parameters. The block contains
calls to the DSL described by <a
href="Interface/ToListDSL.html">Hoodoo::Services::Interface::ToListDSL</a>.
The default values should be described by your platform&#39;s API -
hard-coded at the time of writing as:</p>

<pre><code>limit    50
sort     :created_at =&gt; [ :desc, :asc ]
search   nil
filter   nil
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-to_list_source')" id="l_method-i-to_list_source">show</a>
              </p>
              <div id="method-i-to_list_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 452</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">to_list</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Interface</span><span class="ruby-operator">::</span><span class="ruby-constant">ToListDSL</span>.<span class="ruby-identifier">new</span>(
    <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">instance_variable_get</span>( <span class="ruby-string">&#39;@to_list&#39;</span> ),
    <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>
  )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-to_update">
              <b>to_update</b>( &amp;block )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-to_update" name="method-i-to_update" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>As <a href="Interface.html#method-i-to_create">to_create</a>, but applies
when modifying existing resource instances. To avoid repeating yourself, if
your modification and creation parameter requirements are identical, call
<a
href="Interface.html#method-i-update_same_as_create">update_same_as_create</a>.</p>

<p>The “required” flag is ignored for updates, because an omitted field for an
update to an existing resource instance simply means “do not change the
current value”. As with <a
href="Interface.html#method-i-to_create">to_create</a>, default values have
relevance to the rendering stage only and have no effect here.</p>
<dl class="rdoc-list note-list"><dt>&amp;block
<dd>
<p>Block, passed to <a
href="../Presenters/Object.html">Hoodoo::Presenters::Object</a>, describing
the fields used for resource modification.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-to_update_source')" id="l_method-i-to_update_source">show</a>
              </p>
              <div id="method-i-to_update_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 518</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">to_update</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">obj</span> = <span class="ruby-constant">Class</span>.<span class="ruby-identifier">new</span>( <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span> )
  <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">schema</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )

  <span class="ruby-comment"># When updating, &#39;required&#39; fields in schema aren&#39;t required; you just</span>
  <span class="ruby-comment"># omit a field to avoid changing its value. Walk the to-update schema</span>
  <span class="ruby-comment"># graph stripping out any such problematic attributes.</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">walk</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">property</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">property</span>.<span class="ruby-identifier">required</span> = <span class="ruby-keyword">false</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:to_update=</span>, <span class="ruby-identifier">obj</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-update_same_as_create">
              <b>update_same_as_create</b>()
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-update_same_as_create" name="method-i-update_same_as_create" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declares that the expected JSON fields described in a <a
href="Interface.html#method-i-to_create">to_create</a> call are the same as
those required for modifying resources too.</p>

<p>Example:</p>

<pre><code>update_same_as_create
</code></pre>

<p>…and that&#39;s all. There are no parameters or blocks needed.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-update_same_as_create_source')" id="l_method-i-update_same_as_create_source">show</a>
              </p>
              <div id="method-i-update_same_as_create_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 542</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">update_same_as_create</span>
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:to_update</span>, <span class="ruby-operator">&amp;</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">to_create</span>().<span class="ruby-identifier">get_schema_definition</span>() )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-version">
              <b>version</b>( major_version )
            <a href="../../../classes/Hoodoo/Services/Interface.html#method-i-version" name="method-i-version" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declare the <em>major</em> version of the interface being implemented. All
service endpoints appear at “/v{version}/{endpoint}” relative to whatever
root an edge layer defines. If a service interface does not specifiy its
version, <code>1</code> is assumed.</p>

<p>Two interfaces can exist on the same endpoint provided their versions are
different since the resulting route to reach them will be different too.</p>
<dl class="rdoc-list note-list"><dt><code>version</code>
<dd>
<p>Integer major version number, e.g <code>2</code>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-version_source')" id="l_method-i-version_source">show</a>
              </p>
              <div id="method-i-version_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/services/services/interface.rb, line 297</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">version</span>( <span class="ruby-identifier">major_version</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">send</span>( <span class="ruby-value">:version=</span>, <span class="ruby-identifier">major_version</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">to_i</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
